import { PackageManagerTabs } from '@theme';

# 快速上手

通过本章节来了解如何快速上手并使用 Rspack。

- [创建新项目](#创建新项目)：使用 CLI 创建一个全新的 Rspack 或 Rsbuild 项目。
- [从现有项目迁移](#从现有项目迁移)：从一个基于 webpack 的项目迁移到 Rspack。

## 生态

作为一个底层打包工具，Rspack 拥有丰富的技术生态，包含多种框架、工具和解决方案。这些生态项目涵盖了从框架到开发工具的各个方面，能够满足不同场景下的开发需求，提供开箱即用的体验。

查看 [生态](/guide/start/ecosystem) 页面来探索这些生态项目。

## 环境准备

Rspack 支持使用 [Node.js](https://nodejs.org/)、[Deno](https://deno.com/) 或 [Bun](https://bun.sh/) 作为 JavaScript 运行时。

你可以参考以下安装指南，选择其中一种运行时：

- [安装 Node.js](https://nodejs.org/zh-cn/download)
- [安装 Bun](https://bun.com/docs/installation)
- [安装 Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip 版本要求

Rspack 对于 Node.js 的版本要求如下：

- `@rspack/cli >= v1.0.0` 要求 Node.js 18.12.0 或更高版本。
- `@rspack/core >= v1.5.0` 要求 Node.js 18.12.0 或更高版本。
- `@rspack/core < v1.5.0` 要求 Node.js 16.0.0 或更高版本。

:::

## 创建新项目

### 使用 Rsbuild

Rsbuild 是由 Rspack 驱动的高性能构建工具，由 Rspack 团队开发。它默认包含了一套精心设计的构建配置，提供开箱即用的开发体验，并能够充分发挥出 Rspack 的性能优势。

我们推荐使用 [Rsbuild](https://rsbuild.rs/) 来创建新项目，执行如下命令即可：

<PackageManagerTabs command="create rsbuild@latest" />

> 更多信息参考 [Rsbuild - 快速上手](https://rsbuild.rs/zh/guide/start/quick-start)。

### 使用 Rspack CLI

Rspack CLI 是对标 webpack CLI 的工具，提供基础的 `serve` 和 `build` 构建命令。

执行如下命令即可创建基于 Rspack CLI 的项目：

<PackageManagerTabs command="create rspack@latest" />

然后按照提示操作。

### 非交互模式

[create-rspack](https://www.npmjs.com/package/create-rspack) 和 [create-rsbuild](https://www.npmjs.com/package/create-rsbuild) 支持通过命令行选项进入非交互模式。使用该模式可以跳过所有提示，直接创建项目，适合脚本、CI 以及 coding agents 等自动化场景。

例如，以下命令将在 `my-app` 目录中创建一个 React 应用：

```bash
# Rspack CLI
npx -y create-rspack --dir my-app --template react
# Rsbuild
npx -y create-rsbuild --dir my-app --template react
# 使用缩写
npx -y create-rsbuild -d my-app -t react
```

## 在线示例

我们提供了基于 Rsbuild 的在线示例，通过示例项目，你可以直观感受 Rspack 的构建性能和 Rsbuild 的开发体验：

- [Rsbuild CodeSandbox 示例](https://codesandbox.io/p/github/rspack-contrib/rsbuild-codesandbox-example)

同时我们也提供了基于 Wasm 和 WebContainers 的 StackBlitz 在线示例：

- [Rsbuild StackBlitz 示例](https://stackblitz.com/~/github.com/rspack-contrib/rsbuild-stackblitz-example)

## 手动安装

首先创建一个项目目录，并生成一个 npm `package.json` 文件：

```bash
mkdir rspack-demo
cd rspack-demo
npm init -y
```

然后安装 [@rspack/core](https://www.npmjs.com/package/@rspack/core) 和 [@rspack/cli](https://www.npmjs.com/package/@rspack/cli) 为 dev 依赖：

<PackageManagerTabs command="add @rspack/core @rspack/cli -D" />

更新构建脚本以使用 Rspack CLI：

```js title="package.json"
{
  "scripts": {
    "dev": "rspack dev",
    "build": "rspack build",
    "preview": "rspack preview"
  }
}
```

接下来，查看 [配置 Rspack](/config/index) 来了解如何配置 Rspack。

## 从现有项目迁移

如果你需要从一个现有项目迁移迁移到 Rspack 技术栈，可以参考以下指南：

- [从 webpack 迁移到 Rspack](/guide/migration/webpack)
- [从 webpack 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/webpack)
- [从 Create React App 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/cra)
- [从 Vue CLI 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/vue-cli)
- [从 Vite 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/vite)
- [从 Tsup 迁移到 Rslib](https://rslib.rs/zh/guide/migration/tsup)
- [从 Storybook 迁移](/guide/migration/storybook)

## 安装 canary 版本

当你需要测试或验证 Rspack 未发布至稳定版的功能时，可能需要使用 canary 版本。

Rspack canary 版本的 scope 会带有 `-canary` 后缀。例如 `@rspack/core` 的 canary 包名为 `@rspack-canary/core`。要使用这些版本，你可以配置包管理器（npm/yarn/pnpm/bun）的 overrides。

以下是使用 pnpm overrides 的示例：

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-canary/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

此外，Rspack 社区提供了 [install-rspack](https://github.com/rspack-contrib/install-rspack) 工具来方便地安装 canary 版本：

```shell
npx install-rspack --version latest # 安装当前的 latest 版本
npx install-rspack --version canary # 安装当前的 canary 版本
npx install-rspack --version 1.0.0-canary-d614005-20250101082730 # 安装指定的 canary 版本
```
